VFSdos Developer

VFSdos Developer's manual

April 6, 2003.

You can create your very own VFSdos applications that you can run under VFSdos with the tools provided in this archive. However, you will need the OnBoardC compiler and a Palm DOC editor of your choice. All source code included here is in Palm DOC format. In the TEXT subdirectory you will find the source code in plain text format. The tools where intended to be used directly on a Palm handheld.

Who develops VFSdos applications and why? DOS programmers (like myself) miss the good old DOS days where all you needed to develop an application was a simple editor, a simple C compiler such as Turbo C for DOS and a cup of coffee. Simple enough, you could create simple applications within minutes. VFSdos tries to bring that back into the Palm environment. DOS programmers will immediatly find themselves familiar with the VFSdos programming environment. Functions such as 'printf', 'getch', 'fopen' are back! There is no graphical user interface to bother with! Your application simply spits out the results to a 40x26 scrollable console (or 80x53 on a PalmOS 5 device), just like the old days! What's even more amazing, many simple DOS source codes can be re-compiled using the StdioLib tools with little or no modifications at all. I have written myself a few simple VFSdos applications and their source code is directly compiled as-is on both platforms: DOS and Palm.

The VFSdos developer's tools have been completely re-written as a shared library file by Philippe Guillot. Philippe was kind enough to not only re-write the complete VFSdos library as a shared library file, but he also added many new functions and enhancements as well. The size of the executables has now been reduced by half, and compilation time is now much faster while developing. Merci Philippe! The source code of the shared library is also available in this archive: STDIOSRC.ZIP

Installation:

* VERY IMPORTANT:

First make sure to have installed the OnBoardC compiler (OnBoardC & OnBoardAsm) and the OnBoardHeaderV35.h.pdb header file. DO NOT install the other OnBoardHeader.h.pdb file, otherwise the compiler will report errors when compiling VFSdos source code.

Minimum installation (no development):

VFSDOS.PRC: The VFSdos console application.

DEMO.C.PDB: The VFSdos sample source code used by demo.exe

DEMO.EXE.PRC: Pre-compiled VFSdos sample application for VFSdos.

STDIOLIB.PRC: The VFSdos STDIO library (required by all VFSdos applications).

Additional files required for OnBoardC development:

STDIO.H.PDB: The stdio interface header file

STDIO.C.PDB: The stdio interface source file

STDIO.RSRC.PDB: The stdio resource file

VFSMGR.H.PDB: The VFS API header file

DEMO.C.PDB: The demo application source code

DEMO.PROJ.PRC: The demo project file

* The rest of the files in the archive are the source code and project file of the StdioLib shared library and VFSdos console.

Once you have installed and executed VFSdos, type 'demo' at the command line to run the sample VFSdos demo application. You'll need a DOC editor to view and edit the DEMO.C source code. I recommend QEdit. The source code has been formatted for Qedit in 40x24 mode.

To re-compile the demo application, install all of the above files (stdio header, source and resource files, the VFSmgr.h file, and the demo source and project files).

VFSdos programming guidelines and tips

VFSdos applications use a 40x26 or 80x53 (OS5) character screen for output and command line input via graffiti or external keyboard. If you use the provided library functions, you can take your source code and also compile and run it under Borland's TurboC ++ on your PC.

Here are some guidelines/tips when creating VFSdos applications:

1.Include the stdio.h header file at the beginning of your application's source code.

2.Include both stdio.rsrc and stdio.c files into your application's project file.

3.Make sure 'StdioLib.prc' is installed/bundled with your VFSdos application.

4.Your application must be of type 'pdos' and have the creator ID of 'pDOS'

5.Handle malloc() with care - PalmOS reserves very little RAM and stack space for a running application.

6.Name your application in all small letters (no capitals). The reason is that PalmOS filenames are case sensitive.

7.Append ".exe" to your application name.

8.Use a "press any key to continue" mechanism before your program ends, if it has important residual information on the screen (PalmOS erases the screen when an application quits).

9.You can only pass up to 15 arguments to your application from the VFSdos command line.

10.Include a user abort mechanism on time consuming routines. The reason is that while your application is doing a lengthy operation, PalmOS has no control of the hardware - thus the power button and the hardware buttons won't respond. PalmOS is called while VFSdos waits for user input only (gets() and getc() routines). You can use the UserAbort() function which polls for user intervention without blocking the program flow (non blocking).

10.Use the 'cfcard' global variable (not TurboC standard) to test the presence of a CF card/slot, if your application is using it. This variable returns 1 if card is present, 0 otherwise.

* You can use the included demo source code and project file as a template to start a new VFSdos application.

Currently available (Turbo C compatible) VFSdos library functions
(see the TurboC for DOS documentation for more information)

1. Keyboard input functions:

Function : char *gets(char *buffer);
Details : Waits for the user to enter a string from the keyboard. Input is terminated by ENTER.

Function : char getch(void);
Details : Waits for the user press a keyboard button and returns the pressed key (via graffiti)

2. Screen output functions:

Function : printf(char *fmt,...);
Details : standard printf function

Function : void putch(char c);
Details : print the character c on the screen.

Function : void puts(char *s);
Details : print the string s on the screen.

Function : void clrscr(void);
Details : clear the screen.

Function : void gotoxy(int x,int y);
Details : position the cursor at x,y screen coordinates.

Function : void textmode(int mode);
Details : change screen mode:

Modes:

BW40: 20 column display

BW80: 40 column display

CO40: 20 column color display

CO80: 40 column color display

Function : void setcolor(int color);
Details : sets the text color

Function : void setbkcolor(int color);
Details : sets the text background color.

3. String functions:

Function : char *itoa(int v,char *buffer,int base);
Details : Return a string representation of an integer.

Function : char *ltoa(long v,char*buffer,int base);
Details : Return a string representation of a long integer with a given base.

Function : char *strcat(char *d,char *s);
Details : Appends string 's' to string 'd' and returns a pointer to 'd'

Function : char *strcpy(char *d,char *s);
Details : Copies string 's' to string 'd'. Returns pointer to 'd'

Function : char *strupr(char *s);
Details : Converts 's' to upper case. Returns pointer to converted 's'

Function : int atoi(char *buffer);
Details : Return integer value of string

Function : int strlen(char *s);
Details : Returns the size of the given string

Function : int strstr(char *s, char *k);
Details : Checks if string k is included in string s. Returns true if it is.

Function : long atol(char *s);
Details : Converts string 's' to long. Returns long integer

Function : int strcmp(char *s1,char *s2);
Details : Compare strings s1 and s2.

Returns:
0: s1==s2
1: s1>s2
-1: s1<s2

Function : char *ftoa(float f, char *buf);
Details : Convert float to string (prec:2 decimals)

Function : float atof(char *s);
Details : Convert string to float

4.Memory allocation functions:

Function : void *malloc(int size);
Details : allocate 'size' bytes of memory. Handle with care! Palm allocates little memory to the running application.

Function : void free(void *p);
Details : free previously allocated memory with malloc()

Function : int exit(int code);
Details : exit VFSdos application and return code.

Function : long coreleft(void);
Details : returns free memory

Function : long stackavail(void);
Details : returns available stack

5. Floating point/math functions:

Function : char *ftoa(float f, char *buf);
Details : Convert float to string (prec:2 decimals)

Function : float atof(char *s);
Details : Convert string to float

Function : float fabs(float f);
Details : return absolute value of float

Function : int srand(long seed);
Details : changes random number seed

Function : int rand(void);
Details : return a random number

6. File operation functions (expansion card access only)

NOTE: due to VFS file system calls, use 'long' integers as handles.

Function : int close(long h);
Details : Close a file with the given handle. Works on CF card only.

Function : long open(char *fname, int flags, int mode);
Details : Open a file, return handle. Works on CF card only.

Flags:
O_RDONLY Open for read only
O_WRONLY Open for write only
O_RDWR Read/write access allowed.
O_APPEND Seek to eof on each write
O_CREAT Create the file if it does not exist.
O_BINARY Ignored. All file access is binary

Modes:
S_IREAD Read permitted
S_IWRITE Write permitted

Function : long read(long h,void *buf,long size);
Details : Read 'size' bytes from 'h' file handle into buffer. Returns #of bytes read.

Function : int remove(char *fname);
Details : Delete a file on the expansion card

Function : int rename(char *oldname,char *newname);
Details : Rename a file on the expansion card

Function : long write(long h,void *buf,long size);
Details : Write 'size' bytes to 'h' file handle from buffer. Returns #of bytes written. Works on expansion card only.

Function : long lseek(int h,long offset,int origin);
Details : Seek the 'h' file pointer to the specified direction and origin.

SEEK_SET offset from begining of file
SEEK_CUR offset from current file pointer
SEEK_END offset from end of file

7. File stream functions (RAM only)

NOTE: Files created/opened in RAM by these functions are in DOC format.You can use 'stderr' and 'stdout' as well.

Function : FILE *fopen(char *filename, char *mode);
Details : Opens/creates a DOC file in "r" read or "w" write mode with a given filename. Returns pointer to stream.

NOTE: The 'FILE' structure is not standard, so you should not access its members. Use it only as a handle for the open stream.

Function : int feof(FILE *pF);
Details : Returns non zero when end of file (EOF) is reached.

Function : int fclose(FILE *stream);
Details : Close a previously opened stream (DOC file)

Function : int fprintf(FILE *stream, char *format, argument, ...);
Details : Standard fprintf function (writes to an open stream or stderr/stdout).

Function : char *fgets(char *s, int n, FILE *stream);
Details : Get a string of size 'n' from an open stream (DOC file)

Function : int fputs(char *s, FILE *stream)
Details : write a string to an open stream (DOC file)

8. Other functions (not all TurboC compatible):

Function : char *getdate(char *s);
Details : returns the current date in string 's'

Function : beep(void);
Details : beeps the speaker

Function : int UserAbort(void);
Details : returns 1 if the user taps left side of the graffiti area.

Create a directory:
int mkdir(char *dirname)

Delete a directory:
int rmdir(char *dirname)

Change directory:
int chdir(char *path)

Get current working directory:
char *getcwd(char *buf, int buflen)

Get disk (CF) free space (non standard):
long getdfree(void)

NEW StdioLib (standard) functions now available in version 2.0 and above:

int fread(void *pData,unsigned int size,unsigned int blocks,FILE *pF); // read data blocks from file (DOC format).
int fwrite(void *pData,unsigned int size,unsigned int blocks,FILE *pF); // write data blocks to file (DOC format).
int isalpha(int c); // returns true if c = alphanumeric character.
int toupper(int c);
int isdigit(int c);
int tolower(int c);
int fputc(int c,FILE *pF); // write c into file
long strtol(char*,char**,int);
double strtod(char*,char**);

unsigned int StdioVersion(void); // Returns StdioLib version in Hex format. Ex: 0x203 = Version 2.03

Acknowledgements:

I would like to thank Philippe Guillot for porting the VFSdos developer's library into the StdioLib shared library file, and for adding many new functions making the library more usefull and easier to use. Without his work, the library would have remained as a bunch of source code files. Thank you Philippe, your work is very much appreciated!

I would also like to thank Laurent Thaler for providing the VFSmgr header file.

January. 29th, 2003.

Harry Konstas.